home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / UTILITY / BF202A.ARJ / BNFAPI.DOC < prev    next >
Text File  |  1991-11-26  |  10KB  |  256 lines
  1.              Back & Forth Professional API for upcoming release of v2.00
  2.  
  3.    Back & Forth Professional versions 1.25 and later are fully compatible
  4. with the DOS 5 API task switcher standard as documented in the Microsoft
  5. DOS 5 technical reference manual. Please consult it for further information/
  6. examples.
  7.  
  8.    Back & Forth Professional also supplies a set of API calls for further
  9. control of its environment. All Back & Forth Professional API calls 
  10. originate through interrupt 12h. To initiate an API call, the registers 
  11. should be filled as follows:
  12.  
  13. AX = 0fffeh
  14. CX = 0fffeh
  15. BX = function #
  16.  
  17. DX, ES, and DI may also be needed depending on function call.
  18.  
  19.                  Back & Forth Professional API Calls
  20.  
  21. Function #: 0  --  B&F Pro installed request.
  22.  
  23. Parameters: AX = 0ffffe
  24.             CX = 0ffffe
  25.             BX = 0
  26.  
  27. Returned  : AX = 1 if B&F Pro installed
  28.  
  29. ────────────────────────────────────────────────────────────────────────────
  30. Function #: 1  --  Reserved.
  31.  
  32. ────────────────────────────────────────────────────────────────────────────
  33. Function #: 2  --  Get memory stats.
  34.  
  35. Parameters: AX = 0ffffe
  36.             CX = 0ffffe
  37.             BX = 2
  38.  
  39. Returned  : AX = amount of available swap memory in kilobytes.
  40.             BX = maximum task size in kilobytes.
  41.             DX = fixed overhead per task.
  42.  
  43. ** NOTE **  Fixed overhead does NOT include video saving/restoring, program
  44.             code/data, or macro memory if macros are enabled in EMS memory.
  45.  
  46. ────────────────────────────────────────────────────────────────────────────
  47. Function #: 3  --  Switch task by ID value
  48.  
  49. Parameters: AX = 0ffffe
  50.             CX = 0ffffe
  51.             BX = 3
  52.             DX = Task ID value (see function 7 for makeup of ID)
  53.  
  54. Returned  : AX = 1 task switch will occur as soon as DOS is safe
  55.             AX = 0 invalid task ID.
  56.  
  57. ────────────────────────────────────────────────────────────────────────────
  58. Function #: 4  --  Reserved.
  59.  
  60. ────────────────────────────────────────────────────────────────────────────
  61. Function #: 5  --  Reserved.
  62.  
  63. ────────────────────────────────────────────────────────────────────────────
  64. Function #: 6  --  B&F Pro version #
  65.  
  66. Parameters: AX = 0ffffe
  67.             CX = 0ffffe
  68.             BX = 6
  69.  
  70. Returned  : AX = version #
  71.  
  72.             Major version # = AX / 100
  73.             Minor version # = AX % 100
  74.  
  75. ────────────────────────────────────────────────────────────────────────────
  76. Function #: 7  --  Spawn a program. BF_SPAWN record is passed in ES:DI
  77.  
  78. Parameters: AX = 0ffffe
  79.             CX = 0ffffe
  80.             BX = 7
  81.             ES = segment of BF_SPAWN record
  82.             DI = offset  of BF_SPAWN record
  83.  
  84. Returned  : AX = 1 spawn will take place when it is safe
  85.             AX = 0 no task handles available!
  86.  
  87. ────────────────────────────────────────────────────────────────────────────
  88. Function #: 8  --  Get active task list. 
  89.  
  90. Parameters: AX = 0ffffe
  91.             CX = 0ffffe
  92.             BX = 8
  93.             ES = segment of task storage area
  94.             DI = offset  of task storage area
  95.  
  96. Returned  : AX = # of tasks loaded
  97.  
  98. ** NOTES ** The STORAGE AREA must be at least sizeof(BF_TASK) * 21 or you
  99.             will have serious problems on your hand!
  100.  
  101.             See OEMTEST.C for a complete example of this function.
  102.  
  103. ────────────────────────────────────────────────────────────────────────────
  104. Function #: 9  --  Reserved.
  105.  
  106. ────────────────────────────────────────────────────────────────────────────
  107. Function #: 10  --  Return active clipboard filename.
  108.  
  109. Parameters: AX = 0ffffe
  110.             CX = 0ffffe
  111.             BX = 10
  112.  
  113. Returned  : DX:AX makes up a far ptr to a '\0' terminated filename.
  114.  
  115. ** NOTE ** The cut/paste file is NOT in ASCII format... the next release
  116.            of this document will have sample code to read/write B&F Pro
  117.            clipboard files.
  118.  
  119. ────────────────────────────────────────────────────────────────────────────
  120. Function #: 11  --  Get active task #.
  121.  
  122. Parameters: AX = 0ffffe
  123.             CX = 0ffffe
  124.             BX = 11
  125.  
  126. Returned  : AX = Active task # in range of 0 to 19. Information about the
  127.                  task can be obtained by using this value as an offset into
  128.                  the active task list (See function 8).
  129.             BX = # of tasks allocated
  130.             DX = Max # of tasks
  131.  
  132. ────────────────────────────────────────────────────────────────────────────
  133. Function #: 12  --  Reserved.
  134.  
  135. ────────────────────────────────────────────────────────────────────────────
  136. Function #: 13  --  Reserved.
  137.  
  138. ────────────────────────────────────────────────────────────────────────────
  139. Function #: 14  --  Reserved.
  140.  
  141. ────────────────────────────────────────────────────────────────────────────
  142. Function #: 15  --  Put a '\0' terminated string of characters into the 
  143.                     B&F Pro's internal keyboard buffer.
  144.  
  145. Parameters: AX = 0ffffe
  146.             CX = 0ffffe
  147.             BX = 15
  148.             ES = segment of string
  149.             DI = offset of string
  150.  
  151. Returned  : Nothing.
  152.  
  153. ────────────────────────────────────────────────────────────────────────────
  154. Function #: 16  --  Is current video mode a text mode
  155.  
  156. Parameters: AX = 0ffffe
  157.             CX = 0ffffe
  158.             BX = 16
  159.  
  160. Returned  : AX = -1 Graphics mode
  161.             AX = 0  Color text mode
  162.             AX = 4  Mono  text mode
  163.  
  164. ────────────────────────────────────────────────────────────────────────────
  165. Function #: 17  --  B&F Pro user #
  166.  
  167. Parameters: AX = 0ffffe
  168.             CX = 0ffffe
  169.             BX = 17
  170.  
  171. Returned  : AX = user # from 0 to 255
  172.  
  173. ────────────────────────────────────────────────────────────────────────────
  174. Function #: 18  --  Switch task by task_no into active task list
  175.  
  176. Parameters: AX = 0ffffe
  177.             CX = 0ffffe
  178.             BX = 18
  179.             DX = Task # (see function 8 for obtaining active task list)
  180.  
  181. Returned  : AX =  1 task switch will occur as soon as DOS is safe
  182.             AX =  0 an attempt was made to switch to the active task!
  183.             AX = -1 the task # was invalid
  184.  
  185. ────────────────────────────────────────────────────────────────────────────
  186. Function #: 19  --  Delete task.
  187.  
  188. Parameters: AX = 0ffffe
  189.             CX = 0ffffe
  190.             BX = 18
  191.             DX = Task # (see function 8 for obtaining active task list)
  192.  
  193. Returned  : AX =  1 task was deleted successfully.
  194.             AX =  0 an attempt was made to delete the active task!
  195.             AX = -1 the task # was invalid
  196.  
  197. ** Note **  If you delete a task that was lower in the task list than the
  198.             active task, the active task # will change! Use function call
  199.             11 to regain active task #.
  200.  
  201. ────────────────────────────────────────────────────────────────────────────
  202. Function #: 20  --  Get next available task handle
  203.  
  204. Parameters: AX = 0ffffe
  205.             CX = 0ffffe
  206.             BX = 20
  207.  
  208. Returned  : AX =  1 to xx next available task handle
  209.             AX = -1 task table is full.
  210.  
  211. ** NOTE **  This function can be used to build a hot key, etc. If a task
  212.             is NOT spawned immediately after this call, the task handle #
  213.             returned may become invalid.
  214.  
  215.             Back & Forth Professional API Data Structures
  216.  
  217. 1) BF_SPAWN record used in function 7.
  218.  
  219.    typedef struct
  220.    {
  221.      char description[21];         /* Task description                       */
  222.      char disable_hot_keys;        /* On/off - some applications can't afford*/
  223.      int  environment_size;        /* to be bothered.                        */
  224.                                    /* Size of environment in bytes.          */
  225.      char kb_flags;                /* Hotkey kbflags ALT,LSHIFT,RSHIFT,CTRL  */
  226.      int  key_code;                /* Key code as retrieved at the int 9h    */
  227.                                    /* level.                                 */
  228.      int  max_ems_pages;           /* Not implemented in OEM versions of     */
  229.                                    /* kernel.                                */
  230.      int  memory_needed;           /* Needed memory in K.                    */
  231.      char program_id[3];           /* Two letter Desqview style ID           */
  232.      char program_name[13];        /* Name of program without path. EXE,COM, */
  233.                                    /* or BAT extension must be supplied or   */
  234.                                    /* program won't run!                     */
  235.      char program_path[66];        /* Directory where program can be found.  */
  236.      char work_path[66];           /* Initial path to start program in. If   */
  237.                                    /* not specified, work path will be set   */
  238.                                    /* to the program path.                   */
  239.    } BF_SPAWN;
  240.  
  241.  
  242. 2) BF_TASK record used in function 8.
  243.  
  244.    typedef struct                  /* Record B&F passes back about live tasks*/
  245.    {
  246.      time_t actual_start_time;     /* Actual start time of program           */
  247.      char   description[21];       /* Task description                       */
  248.      time_t elapsed_time;          /* Actual time spent in task              */
  249.      int    id;                    /* Task id                                */
  250.      char   kb_flags;              /* Keyboard flags component of task hotkey*/
  251.      int    key_code;              /* Keyboard code component of task hotkey */
  252.      time_t stop_time;             /* Time task was suspended/exited         */
  253.      int    task_handle_no;        /* B&F assigned task handle.. used to     */
  254.                                    /* individual tasks!                      */
  255.    } BF_TASK;
  256.